home *** CD-ROM | disk | FTP | other *** search
/ Macwelt 1 / Macwelt DVD 1.toast / Web-Publishing / HTML-Editoren / Alpha ƒ / Help / Help Files Help < prev    next >
Encoding:
Text File  |  2000-11-30  |  15.2 KB  |  451 lines
  1.  
  2. Help Files Help 
  3.  
  4.  
  5.                                                version: 1.3
  6.                                                created: 07/17/00 {12:22:13 pm}
  7.                                            last update: 11/30/00 {08:14:50 pm}
  8.  
  9.  
  10.  
  11.           Introduction
  12.  
  13.  
  14. This document deals with three different topics.  The first provides 
  15. information on Alpha's auto-marking / hyperizing routines for Help files.  
  16. The second introduces "AlphaBits", a forum for addressing user questions 
  17. and improving Alpha's documentation.  The third poses possibilities for 
  18. future directions of Alpha's help facilities.
  19.  
  20.  
  21.           Listservs devoted to Alpha
  22.  
  23.  
  24. There are two listservs set up to support Alpha's development and use.  The
  25. first, known as Alpha-D (for Alpha Developers) is where one can suggest
  26. improvements for Alpha or its Tcl library, and to discuss bugs.  To
  27. subscribe, email <LISTSERV@LISTSERV.SYR.EDU> and, in the text of your
  28. message (not the subject line), write:
  29.  
  30.     SUBSCRIBE ALPHA-D
  31.  
  32. (See also the help file "Bug Reports and Debugging".  Alpha has a
  33. sophisticated bug reporting and tracking system, at
  34.  
  35.     <http://www.maths.mq.edu.au/~steffen/bugzilla/>
  36.  
  37. Please use Bugzilla, since it will help us (and you) to keep track of bugs,
  38. potential workarounds, and when they are finally fixed.)
  39.  
  40. The second listserv is called AlphaBits, and is intended for a less
  41. technical audience (i.e. the typical Alpha user that simply wants to know
  42. how to use the program more efficiently.)  This is also a forum for
  43. discussing Alpha's documentation, and to submit suggestions for various
  44. Help files.  To subscribe, email Donavan Hall at <hall@magnet.fsu.edu> and
  45. let him know that you want to sign up.
  46.  
  47.           
  48.     ======================================================================
  49.  
  50.  
  51.           Auto Marking Help Files
  52.  
  53.  
  54. Alpha v 7.4 has introduced auto-marking / hyperizing capabilities for Help
  55. files.  If a file that contains no colors is opened through the Help Menu,
  56. Alpha will go through a series of hyperizing / marking routines using
  57. help::colourHeadingsEtc (in "help.tcl").
  58.  
  59. Auto-marking / hyperizing files must be "clean" before they are opened
  60. through the Help menu -- that is, they must not have any colors or hypers
  61. in them.  If this is the case, Alpha will mark the file and perform a
  62. series of "search and hyperize" routines following the guidelines below.
  63.  
  64. These routines makes writing Help files much easier -- no need to
  65. individually "Link To File" anymore !!  (This means that help files can
  66. also be marked and hyperized by Alphatk.)
  67.  
  68. Help files will only be auto-marked / hyperized once, and then the hypers
  69. will be saved in the resource fork.  (Note: This will not change the "save"
  70. date of the file.  Installation of future versions of Alpha can still
  71. overwrite older existing files.)
  72.  
  73. See these "Alpha Developers --> Marking" menu item procedures for details
  74. on what these auto-marking / hyperizing routines actually do:
  75.  
  76.  
  77.     proc: help::hyperiseEmailAddresses
  78.     proc: help::hyperiseUrls
  79.     proc: help::colourHeadingsEtc
  80.  
  81.  
  82. The proc: help::openDirect uses these procedures, setting additional window
  83. information (read-only 1, dirty 0, tabsize 4).  The Help file is then
  84. closed and re-opened.
  85.  
  86. The following sections describe the syntax required to achieve marks, 
  87. hypers and colors in these files.  Note:  there is an additional marking 
  88. regime, proc: help::markTclCommands, that might be used instead for 
  89. particular files.  See the "Exceptions" section below.
  90.  
  91.  
  92.                Marks
  93.  
  94.  
  95. To create a mark, start the line with <tab><space><space><tab>.  This will
  96. be stripped from the mark name.  Subsequent spaces and tabs will indent the
  97. mark's name, which is useful for sub-sections.  (Note that a tab will
  98. indent only one space.)  If nothing follows the <tab><space><space><tab>, a
  99. section divider will appear in the mark menu, and the next alphanumeric 
  100. line will be colored red and underlined (as if it were a mark.)
  101.  
  102. Note that the proc: help::openDirect will automatically convert tab sizes to 4.
  103.  
  104.  
  105.                Colors
  106.  
  107.         
  108. Any line that begins with one (and only one) tab will be colored blue,
  109.  
  110.     like this.  Subsequent lines that begin with a tab
  111.         will be colored blue as well.
  112.  
  113. The string IMPORTANT: will be colored red, as will menu directions that
  114. include "<something>-><something>":
  115.  
  116.     "File --> Open..."
  117.  
  118.     "Config->Preferences->Suffix Mappings…"
  119.  
  120.     'Text -> Fill Paragraph'
  121.  
  122.     'Alpha Developers Menu --> Marking --> Colour Headings Etc'
  123.  
  124.  
  125. Several variations are allowed, so long as <something>-><something> is
  126. surrounded by either single or double quotes.
  127.  
  128.  
  129.                Hyperlinks
  130.  
  131.  
  132. Hyperlinks are created by the proc: help::colourHeadingsEtc, contained 
  133. in "help.tcl".
  134.  
  135.  
  136.                     Hyperlinks to Installed Files
  137.  
  138.  
  139. To create a hyperlink to most .tcl files, include the file's name in quotes:
  140.  
  141.  
  142.     "htmlMode.tcl"
  143.  
  144.  
  145. To create a hyperlink to most Help files, include the file's name in quotes:
  146.  
  147.  
  148.     "Extending Alpha"    "Alpha Manual"    "Calculator Help"
  149.  
  150.  
  151. Help for specific packages can be hyperlinked in two ways.  The first is to 
  152. precede the package's name with 'package: ', as in package: latexAccents.  
  153. The second way is to surround the package's name in quotes, and add ' Help' 
  154. as in "recentFilesMultiMenu Help".  Thus the BibTeX help file could be 
  155. hyperlinked with all of
  156.  
  157.  
  158.     "BibTeX Help"    package: Bib    "Bib Help" 
  159.     
  160.     package: bibtexMenu    "bibtexMenu Help"
  161.  
  162.  
  163. Completion files and Completion Tutorials can also be hyperlinked:
  164.  
  165.  
  166.     "TclCompletions.tcl"  "Text Tutorial"  "C Tutorial.r"  
  167.  
  168.  
  169.                     Hyperlinks to Examples
  170.  
  171.  
  172. To include an 'example' hyperlink, which will open any file in the Mode
  173. Examples folder in read-only format, simply put the file's name in quotes:
  174.  
  175.     "LaTeX-Example.tex"
  176.  
  177. To open the example in a shell window, which will insert some explanatory
  178. comments at the top of the window and allow for any modifications without
  179. altering the original file, omit the dash preceding Example in the file's 
  180. name:
  181.  
  182.     "LaTeX Example.tex"
  183.  
  184. Note that examples which are opened in shell windows do not technically 
  185. exist as files, and the window will not have any file suffix.  This could 
  186. disable some mode features that rely on file suffixes, and the window can 
  187. not be sent to other applications.
  188.  
  189. If you want to include an example that does something different than these
  190. two default routines, you must create a "<something>-Example.sfx.tcl" file. 
  191. The alpha-specific modes use such scripts (i.e. "Compare Example" sources
  192. "Compare-Example.tcl").  These can also be adapted for package-specific
  193. tutorials, such as the tutorials
  194.  
  195.     "Filters Example"       "Filters-Example.tcl"    and
  196.     "ManipCols Example"     "ManipCols-Example.tcl"
  197.  
  198. See some of the .tcl files in the "Mode Examples" folder for more examples.
  199.  
  200.  
  201.                     Hyperlinks to Prefs Files
  202.  
  203.  
  204. help::colourHeadingsEtc recognizes "<mode>Prefs.tcl" strings.  Thus I
  205. can include the following lines in my "Statistical Modes Help" file:
  206.  
  207.     ----------------------------------------------------------------------
  208.  
  209. To add keywords in a "SASPrefs.tcl" file, include the following commands:
  210.  
  211.     set SASuserCommands {
  212.         blah blahdity etc
  213.     }
  214.     
  215.     ----------------------------------------------------------------------
  216.  
  217. Clicking on the "SASPrefs.tcl" link will prompt the user to create the 
  218. file if necessary.  The string "prefs.tcl" will similarly open the global 
  219. preferences file.
  220.  
  221.  
  222.                     Hyperlinks to Hypertext
  223.  
  224.  
  225. Strings embedded in << >> will be treated as hypertext.  For example,
  226.  
  227.  
  228.     <<wwwParseFile [file join $HOME Help "Electric Corrections Help.html"]>>
  229.  
  230.     <<file::openDefault [file join $HOME Help "Electric Corrections Help.html"]>>
  231.  
  232.  
  233. will send the HTML manual to either Alpha's parser or a browser.
  234.  
  235.  
  236.                     Hyperlinks to Tcl Command Double-click
  237.  
  238.  
  239. When a file is in Tcl mode, command double-clicking on a defined procedure
  240. will open the file in which that proc is contained.  In Help files, the
  241. string proc: <something> will create a hyperlink which does the same, as in
  242.  
  243.  
  244.     proc: Tcl::DblClickHelper
  245.  
  246.  
  247. Very handy for Changes files !  This will also work for Alpha or Tcl
  248. commands, as in proc: regModeKeywords or proc: proc .
  249.  
  250. (An alternative hyperlink "hint" is "command: ", as in command: append or
  251. command: abbrev .  Note that proc: <string> and command: <string> do the
  252. exact same thing, following the orders of precedence in Tcl::DblClickHelper.)
  253.  
  254.  
  255.                     Hyperlinks for Web Applications
  256.  
  257.  
  258. Finally, email and url addresses surrounded by <> will be hyperized as 
  259. well, as in <http://www.alpha.olm.net/> or <cupright@princeton.edu>.
  260.  
  261.  
  262.           Exceptions
  263.  
  264.  
  265. There is an alternative marking routine, proc: help::markTclCommands, that
  266. is used in place of help::colourHeadingsEtc for certain files.  See the
  267. proc: help::openFile for a list of the exceptions.
  268.  
  269. These files will still hyperize e-mails and urls, but marks are based on
  270. any word which follows the string NAME, where NAME is the first word
  271. encountered on a line.  (See "Tcl Commands" for an example.)  Hyperlinks to
  272. additional files, however, are not possible.  The only additional coloring
  273. provided is for lines which contain ALL CAP WORDS, and the file's "title".
  274.  
  275. (The "Alpha Commands" file has it's own marking procedure as well, using
  276. proc: help::markAlphaCommands, which can not be used for any other file.)
  277.  
  278. Important: These routines only apply to Help files in Text mode.
  279.  
  280.  
  281.  
  282.     ----------------------------------------------------------------------
  283.  
  284.  
  285.           Tools to help write Auto-Hyperizing Files
  286.  
  287.  
  288. Using the guidelines outlined above, any "clean" Help file opened through
  289. the Help Menu will auto-mark / hyperize using the routines defined in the
  290. Alpha Developer's Menu.  The window's "dirty" information for will then be
  291. set to "0", then the file will close and reopen.  (See proc: help::openFile
  292. for details.)
  293.  
  294. Please check all of your auto-marking hypers before releasing Help files!
  295.  
  296. To color and mark files, or to remove hypers, use the menu items found in
  297. "Alpha Developers --> Help File Marking".  
  298.  
  299.  
  300.     ----------------------------------------------------------------------
  301.  
  302.  
  303.           Building Alpha's Help Menu
  304.  
  305.  
  306. Items in the Help menu are added only if there is a valid file located in
  307. the Help file in the top level of Alpha's hierarchy.  All file extensions
  308. are stripped from the name, and no duplicates are added.  For example, if
  309. the Help folder includes
  310.  
  311.     Electric Corrections Help
  312.     Electric Corrections Help.html
  313.  
  314. only "Electric Corrections Help" is listed, but when the user tries to open
  315. it a list-pick dialog opens with both of them, plus the parser option
  316.  
  317.     Electric Corrections Help.www
  318.  
  319. Alpha can currently send .html .pdf and .tex files to the appropriate
  320. helper application, using the proc: help::openDirect
  321.  
  322. There are two "Help Menu" preferences that can help limit the options
  323. presented to the user: helpMenuOptions, and viewHtmlUsing.  These are
  324. currently set using the "Config --> Preferences --> WWW" menu.  If there is
  325. only one file, or if the preferences narrow down the options to only one
  326. format, it is sent automatically to the proc: help::openDirect.
  327.  
  328.  
  329.                Exceptions -- .tcl files
  330.  
  331.  
  332. If there is a .tcl file associated with the Help menu item, such as a
  333. 'BibTeX Help.tcl' file in the example above, this file is immediately
  334. sourced.  It is up to the script to decide if more options will be
  335. presented to the user -- the script can choose to ignore the Help Menu
  336. preferences or not.  See the "HTML Help.tcl" or "LaTeX Help.tcl" files for
  337. some examples.
  338.  
  339.  
  340.                Subdirectories in the Help folder
  341.  
  342.  
  343. In versions of Alpha/tk prior to 8.0, the name of any subdirectory in the
  344. Help folder is simply listed as another menu item.  If there is no .tcl
  345. file associated with the menu item, selecting it will offer the user a
  346. list-pick dialog of all items within the subdirectory using the "Help Menu
  347. Options" preferences mentioned above.  
  348.  
  349. In versions 8.0, the name of the subdirectory will be inserted as a submenu
  350. listing the contents of the folder, unless there is an associated .tcl file
  351. present.  In this case, the item will simply appear as another option (as
  352. above), and selecting it will immediately source the .tcl script.
  353.  
  354. So in both versions, if the help file for a particular feature / mode etc
  355. is a complex .html suite (like the HTML mode manual), including a
  356. subdirectory named (for example)
  357.  
  358.     TclAEdoc
  359.  
  360. as well as the script
  361.  
  362.     TclAEdoc.tcl
  363.  
  364. will simply insert "TclAEdoc" in the Help menu, but allow its selection to
  365. do whatever the script wants, including opening any of the files within the
  366. TclAEdoc subdirectory.
  367.  
  368.  
  369.  
  370.     ----------------------------------------------------------------------
  371.  
  372.  
  373.           Documenting Help Files
  374.  
  375.  
  376. Every Help file is a work in progress.  Alpha's features change, and 
  377. documentation that might seem perfectly clear to the programmer might 
  378. make less sense to a user.  I recommend the following guidelines for 
  379. ensuring that documentation can (and will) be regularly updated:
  380.  
  381.     (1)    Include version numbers on all help files.
  382.  
  383. Ideally, this number would correspond to the version number of the mode / 
  384. feature / menu / extension etc.  explained in the Help file.  This way 
  385. future programmers and users will have a much better idea of when a Help 
  386. file might need to be updated.
  387.  
  388.     (2)    Use the Document Projects feature when writing Help files.
  389.  
  390. This feature allows for files to automatically update "save" dates in the 
  391. header.  See the "Documentprojects Help" file for more information.
  392.  
  393.     (3)    Include author / maintainer information for Help files.
  394.  
  395. The author of the package is not necessarily the author of its associated
  396. Help file, and neither of these might be the person who is currently
  397. updating or maintaining the Help file.  Please give credit where it is due,
  398. and include information on where one can send suggestions on the Help file. 
  399. This will make updates much more likely to occur.
  400.  
  401.     (4)    Include any license and disclaimer notes somewhere in the file.
  402.  
  403.  
  404.     ----------------------------------------------------------------------
  405.  
  406.  
  407.           License and Disclaimer
  408.  
  409.  
  410. Redistribution and use in source and binary forms, with or without
  411. modification, are permitted provided that the following conditions are met:
  412.  
  413. Redistributions of source code must retain the above copyright notice, this
  414. list of conditions and the following disclaimer.
  415.  
  416. Redistributions in binary form must reproduce the above copyright notice,
  417. this list of conditions and the following disclaimer in the documentation
  418. and/or other materials provided with the distribution.
  419.  
  420. This software is provided by the copyright holders and contributors "as is"
  421. and any express or implied warranties, including, but not limited to, the
  422. implied warranties of merchantability and fitness for a particular purpose
  423. are disclaimed.  In no event shall the regents or contributors be liable
  424. for any direct, indirect, incidental, special, exemplary, or consequential
  425. damages (including, but not limited to, procurement of substitute goods or
  426. services; loss of use, data, or profits; or business interruption) however
  427. caused and on any theory of liability, whether in contract, strict
  428. liability, or tort (including negligence or otherwise) arising in any way
  429. out of the use of this software, even if advised of the possibility of such
  430. damage.
  431.  
  432.     --------
  433.  
  434. This package is free.  Alpha is shareware !  <<register>>
  435.  
  436.  
  437. Feel free to send me any bugs, comments, or suggestions on this file.
  438.  
  439. cheers,
  440.  
  441.  
  442. -- cbu
  443.  
  444.  
  445. Author: Craig Barton Upright
  446. E-mail: <cupright@princeton.edu>
  447.   mail: Princeton University,  Department of Sociology
  448.         Princeton, New Jersey  08544
  449.    www: <http://www.princeton.edu/~cupright/>
  450.  
  451.